home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 176-200 / scopedisk180 / arexxtutorial / rep_host / report_host.doc < prev    next >
Text File  |  1995-03-19  |  5KB  |  173 lines
  1.               Report Host Documentation
  2.                 Sep 1, 1989
  3.  
  4.  
  5.  
  6. WHO:
  7.  
  8.     Copyright © 1989 by Donald T. Meyer, Stormgate Software
  9.     All Rights Reserved
  10.     This function host may be freely distributed via BBS and Freeware
  11.     collections on diskette.
  12.     Commercial use is with the written consent of Donald T. Meyer only.
  13.  
  14.     Stormgate Software
  15.     P.O. Box 383
  16.     St. Peters, MO  63376
  17.  
  18.     E-Mail can be sent via the following:
  19.     BIX:    donmeyer        (almost daily)
  20.     GEnie:    D.MEYER            (weekly)
  21.     PLINK:    Stormgate        (weekly)
  22.  
  23.  
  24.  
  25. WHAT:
  26.  
  27. An ARexx function host.
  28.  
  29.  
  30.  
  31. DESCRIPTION:
  32.  
  33. This ARexx function host, which is written using my freely distibutable
  34. function host source code (available on various communications services),
  35. contains a set of functions dealing with displaying "report" text.
  36.  
  37. The intent of the "report" functions is to give ARexx programs a
  38. standard way of displaying "verbosity" type messages.  The report level
  39. would be set by the user (via -v5 etc. cmd. line opts?) to control
  40. just what the ARexx program displayed.  For example, level 1 would be
  41. very detailed progress/status messages, level 5 would be general
  42. progress messages, and level 10 might be non-fatal errors.
  43.  
  44. Why do I feel the need to do these sorts of things?  Well, in 'C' for
  45. example, a global variable is truly global.  ARexx on the other hand
  46. does not allow you access to "global" variables in a procedure unless
  47. you EXPOSE them.  For verbosity reports, which may be displayed from
  48. any point in any ARexx function, this limitation (or feature!)
  49. gets annoying.
  50. This function host allows the "global" data, i.e. report stream and level
  51. to be stored external to the ARexx program.  As an added benefit, if you
  52. open the scrollback window, the text will remain after the ARexx program
  53. has exited.  This is handy for ARexx macros launched from the WorkBench.
  54.  
  55. Please send me any bugs, comments, or suggestions that you care to.
  56.  
  57.  
  58.  
  59. TO USE IT:
  60.  
  61. Merely type "report_host" at a CLI, or double-click from WorkBench.
  62.  
  63. When executed, this function host will detach and run in the background
  64. (if started from a CLI, there is no need to "run" or "runback" it).
  65. It will automaticly add itself to the ARexx library list.
  66. This may be started from either CLI or WorkBench, and the normal stack
  67. size of 4096 is just fine.
  68. Once running, the various functions defined herein are accessible
  69. simply by using them in any ARexx program.
  70.  
  71. For more information on ARexx Function Hosts, see Chapter 6 in the
  72. ARexx manual.
  73.  
  74.  
  75. To remove it, simply type "report_host -q" from the CLI, or start it from
  76. the WorkBench again.  It will take itself off of the ARexx library
  77. list and remove itself from memory.
  78.  
  79.  
  80.  
  81. LIST OF FUNCTIONS:
  82.  
  83.     SETREPORT()
  84.     ENDREPORT()
  85.     REPORT()
  86.  
  87.  
  88.  
  89.  
  90.     **********************************************************
  91.     **                            **
  92.     **        Function Descriptions            **
  93.     **                            **
  94.     **********************************************************
  95.  
  96.  
  97.  
  98. ----------------------------------------------------------------------
  99.  
  100.             SETREPORT()
  101.  
  102.  
  103.     call setreport( level, [stream], [header text] )
  104.  
  105. Set the reporting level for messages from the ARexx program.
  106. Level is a number used to control which messages display.
  107. Stream may (currently) be either null or "GLOBAL".  If null, the
  108. report text will first go to the ARexx programs "*" console.  If
  109. this is not available, the text will be sent to the report host's
  110. stream.  The report hosts stream will be the CLI the report host was
  111. started from, or, if that is not available, the report host will open
  112. it's own window.  If the environment variable "REPORT_HOST_OUT" is
  113. set to "scrollback" than a window which allows reviewing historical
  114. text that has scrolled off will be used.
  115. Header text if set will preface all report text.
  116.  
  117.  
  118.  
  119. ----------------------------------------------------------------------
  120.  
  121.             ENDREPORT()
  122.  
  123.  
  124.     call endreport( [ALL] )
  125.  
  126. This should be called at the end of every ARexx program which
  127. calls setreport().  This will free up the data allocated and close
  128. the output stream if neccessary.
  129.  
  130. In some cases, an ARexx program will terminate in a fashion which
  131. does not allow an endreport() call to be made.  If this occurs,
  132. a small amount of memory which was allocated to store information
  133. about the ARexx program will not be freed.  Usually this is not a
  134. great concern.
  135.  
  136. If the ALL keyword is given, this will be done for EVERY program
  137. which has ever setreport()'ed.  This should only be done if it
  138. is neccessary to clean up for some programs which may have exited
  139. without cleaning up for themselves.
  140.  
  141.  
  142.  
  143. ----------------------------------------------------------------------
  144.  
  145.             REPORT()
  146.  
  147.  
  148.     call report( level, text )
  149.  
  150. This will cause the text to be displayed if the 'level' is equal to
  151. or greater than the level set via a call to setreport().
  152.  
  153.  
  154. Example report usage:
  155.  
  156.     call setreport( 5, , "My program says" )    /* Send report text
  157.                                                   * to the ARexx pgms.
  158.                                                  * "*" stream.
  159.                                                  */
  160.  
  161.     call report( 4, "Processing a new file" )    /* won't print, the
  162.                                                  * level is <5
  163.                                                  */
  164.  
  165.     call report( 10, "File was not processed" )
  166.         /* Will print "My program says: File was not processed" */
  167.  
  168.     call endreport()
  169.  
  170.  
  171.  
  172. ----------------------------------------------------------------------
  173.